HOW TO - Implementing the SUBSCRIBE Method in a Resource

Kourier Integrator Online Help

HOW TO - Implementing the SUBSCRIBE Method in a Resource

Requirement for the Default GET Resource Export

Subscriptions are implemented using standard Kourier exports (for GETs) and imports (for POST and DELETE). The Export Specification (referenced in the header of the REST resource) that implements the default GET operation for a resource must adhere to certain requirements if that resource is configured to allow subscriptions. Those requirements are detailed below.

The query parameter that is designated as the “default” parameter must not have any edit which precludes a non-existent item-id from being processed by the export. This is because the endpoint needs to be able to send delete payloads to the call back URL. For example, the “UFILE;CUSTOMER” edit is NOT compatible with REST subscriptions.
The selection criteria for the “default” query parameter must allow a list of item-ids to be processed (e.g. uses the "UVLIST;’" edit). This allows multiple records to be returned when generating the call back payload which can improve performance when a file changes frequently.
Normally the default GET export for a resource does not have any criteria other than a substitution string to form a list of item IDs to be selected. However, on some systems, additional criteria must be specified if the source table is segmented by a “type” field such as the ENTITY file in Eclipse which contains vendors, customers, ship-tos and branches records. Any additional criteria will be honored when generating UPDATE payloads, however this criterion is bypassed with processing DELETE payloads.

Creating the Subscription Import/Export

The KOURIER account has a sample export and import that can be used to implement subscriptions for your REST integration. Use the suitcase tools to move the DEMO_SUBSCRIBE export and import from the KOURIER account into your application account by performing the following steps.

Select the Pack Suitcase option from the Administration menu in the KOURIER account.
Type a name for your suitcase in the Suitcase Name field.
Select the checkbox for the DEMO Integration ID.
Click the Pack button to pack your suitcase. The suitcase file will be saved to the folder location that you have designated in your web browser settings.
Connect to your application account by selecting the Connections option from the Administration menu.
Select the Unpack Suitcase option from the Administration menu in your application account.
Select the Choose File button and navigate to the location where you saved your suitcase, and click the Open button.
Unselect all items.
Select the checkboxes for the DEMO_SUBSCRIBE Component IDs for KT_IMPORTS and KT_EXPORTS. You only need to select these two items.
Click the Unpack icon on the toolbar to unpack your selected components. An Unpack Suitcase Options window appears.
Click the Continue button without selecting any other options. The Unpack Suitcase Results window appears that lists the components that were unpacked from the suitcase.
Click Continue to close the Unpack Suitcase window.
Navigate to the Export Specifications listing, open the DEMO_SUBSCRIBE export specification, and use the Save As button to save it as RWS_SUBSCRIBE.
Navigate to the Import Specifications listing, open the DEMO_SUBSCRIBE import specification, and use the Save As button to save it as RWS_SUBSCRIBE.
In order for the subscription to be aware of the required parameters for the default export, you need to follow the steps below. In the SUBSCRIBE Import Specification you just renamed, make the following changes:

If there are any parameters, other than the default parameter (discussed above) necessary to resolve any of the substitution expressions used in the default GET export (e.g. Location) for the resource, add them now. Be sure to rename the default parameter to a name that is meaningful for your database.
Delete any unwanted parameters in the Import Specification.
Select the Before Read Event Handler and click the button next to it to open the Edit Before Read window. Select all of the text in this window, delete it, and then click the Done button.
If a parameter is required, you may either select the “Required” checkbox in the REST Import Parameters screen or you can implement the required field edit in the Before Read Event Handler. Implementing the required field in the Before Event Handler allows the API consumer to DELETE a subscription without specifying any required fields.

Following is the URL for DELETE if the “Required” checkbox is used:

					http://greenflash.koretech.com:8082/RWS/CUSTOMERS/SUBSCRIBE/10049?Location=T1

Following is the URL for DELETE if the “Required” checkbox is NOT used:

					http://greenflash.koretech.com:8082/RWS/CUSTOMERS/SUBSCRIBE/10049

Adding Subscriptions to a Resource

Subscriptions are implemented like any other sub-resource. Therefore you need to:

Create a sub-resource called SUBSCRIBE using the REST Resource Specification page for the resource(s) you want to allow others to subscribe to. Select the export you created that implements the subscription GET functionality (e.g. RWS_SUBSCRIBE). Select the import you created that implements the subscription POST and DELETE functionality (e.g. RWS_SUBSCRIBE).
Since subscriptions are implemented like any other sub-resource, you must add the sub-resource to any policies on the Kourier REST Gateway that should have access to this capability. Only GET, POST and DELETE HTTP verbs should be enabled.

If all resources in your integration use the same parameter(s) you can use the same import to implement subscriptions across multiple resources.